Skip to content

fix(hotkeys): mac hotkeys follow Apple's Human Interface Guidelines#139

Open
IanWorley wants to merge 3 commits into
TanStack:mainfrom
IanWorley:fix-mac-hotkeys-hig-modifier-order
Open

fix(hotkeys): mac hotkeys follow Apple's Human Interface Guidelines#139
IanWorley wants to merge 3 commits into
TanStack:mainfrom
IanWorley:fix-mac-hotkeys-hig-modifier-order

Conversation

@IanWorley

@IanWorley IanWorley commented Jul 18, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown

🎯 Changes

  • Provide a code change that now displays mac hotkeys in the proper order set out by (Apple's Human Interface Guidelines)[https://developer.apple.com/design/human-interface-guidelines/keyboards]
  • Wrote documentation of said code changes mention above.

✅ Checklist

  • I have followed the steps in the Contributing guide.
  • I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • Improvements
    • Updated macOS hotkey formatting to follow Apple’s Human Interface Guidelines, rendering Shift before Command (including Mod behavior).
    • macOS shortcut symbols now join with spaces; Windows/Linux continue using + formatting.
  • Documentation
    • Refreshed React, Preact, Solid, and Lit guides with updated formatForDisplay/formatWithLabels examples and revised platform symbol reference tables.
  • Tests
    • Updated expected outputs and added macOS coverage for both symbol and text-label formatting order.

@coderabbitai

coderabbitai Bot commented Jul 18, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0eb8fd44-cf25-4c83-a25c-12533d6926bf

📥 Commits

Reviewing files that changed from the base of the PR and between 7811d82 and 7f0efab.

⛔ Files ignored due to path filters (1)
  • docs/reference/functions/formatForDisplay.md is excluded by !docs/**/reference/**
📒 Files selected for processing (7)
  • .changeset/tangy-mangos-clap.md
  • docs/framework/lit/guides/formatting-display.md
  • docs/framework/preact/guides/formatting-display.md
  • docs/framework/react/guides/formatting-display.md
  • docs/framework/solid/guides/formatting-display.md
  • packages/hotkeys/src/format.ts
  • packages/hotkeys/tests/format.test.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • .changeset/tangy-mangos-clap.md
  • docs/framework/react/guides/formatting-display.md
  • packages/hotkeys/src/format.ts
  • packages/hotkeys/tests/format.test.ts
  • docs/framework/lit/guides/formatting-display.md
📝 Walkthrough

Walkthrough

macOS hotkey formatting now orders modifiers as Control → Option → Shift → Command, resolves Mod for macOS before ordering, and updates tests, release metadata, and framework documentation.

Changes

macOS Modifier Ordering

Layer / File(s) Summary
macOS formatter ordering
packages/hotkeys/src/format.ts, .changeset/tangy-mangos-clap.md		 formatForDisplay reorders macOS modifiers using Apple HIG ordering, resolves the macOS Mod alias, and records a patch release.
Formatter ordering tests
packages/hotkeys/tests/format.test.ts		 macOS symbol and label expectations now place Shift before Command, with coverage for symbol and text output. Windows/Linux canonical ordering remains covered.
Framework documentation alignment
docs/framework/*/guides/formatting-display.md		 Lit, Preact, React, and Solid examples, explanations, badge output, and platform reference tables reflect the updated ordering.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

  • TanStack/hotkeys issue 136 — Directly addresses the macOS modifier-ordering bug fixed here.

Poem

A rabbit taps Shift, then Command with care,
Apple-style symbols float through the air.
Tests hop along, docs follow the trail,
Windows keeps its canonical tale.
Format the keys—hip-hop, hooray!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main change: macOS hotkeys now follow Apple HIG ordering.
Description check ✅ Passed The description matches the required template with Changes, Checklist, and Release Impact sections filled in.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@IanWorley IanWorley changed the title fix(hotkeys): mac hotkeys follow Apple's Human Interface Guidelines #136 fix(hotkeys): mac hotkeys follow Apple's Human Interface Guidelines Jul 18, 2026
@IanWorley
IanWorley force-pushed the fix-mac-hotkeys-hig-modifier-order branch from 7811d82 to 7f0efab Compare July 19, 2026 18:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@IanWorley